"""扫描执行器基类"""
from abc import ABC, abstractmethod
from typing import Dict, Any, List, Optional
from dataclasses import dataclass
from datetime import datetime


@dataclass
class ScanContext:
    """扫描上下文"""
    scan_record_id: int
    task_id: int
    task_type: str
    branch: str
    scan_params: Dict[str, Any]
    created_by: Optional[str] = None


@dataclass
class ScanResult:
    """扫描结果"""
    issues: List[Dict[str, Any]]
    summary: Dict[str, Any]
    metadata: Optional[Dict[str, Any]] = None
    
    def __post_init__(self):
        """验证扫描结果"""
        if not isinstance(self.issues, list):
            raise ValueError("issues must be a list")
        if not isinstance(self.summary, dict):
            raise ValueError("summary must be a dict")


class ScanException(Exception):
    """扫描异常"""
    pass


class ScanExecutor(ABC):
    """扫描执行器抽象基类"""
    
    @abstractmethod
    def get_task_type(self) -> str:
        """返回任务类型标识"""
        pass
    
    @abstractmethod
    def validate_params(self, scan_params: Dict[str, Any]) -> bool:
        """
        验证扫描参数
        
        Args:
            scan_params: 扫描参数字典
            
        Returns:
            bool: 参数是否有效
        """
        pass
    
    @abstractmethod
    def execute_scan(self, context: ScanContext) -> ScanResult:
        """
        执行扫描
        
        Args:
            context: 扫描上下文
            
        Returns:
            ScanResult: 扫描结果
            
        Raises:
            ScanException: 扫描执行失败时抛出
        """
        pass
    
    def cancel_scan(self, scan_record_id: int) -> bool:
        """
        取消扫描（可选实现）
        
        Args:
            scan_record_id: 扫描记录ID
            
        Returns:
            bool: 是否成功取消
        """
        return False
    
    def get_supported_extensions(self) -> List[str]:
        """
        返回支持的扩展字段列表
        
        Returns:
            List[str]: 扩展字段名称列表
        """
        return []

